home *** CD-ROM | disk | FTP | other *** search
/ AmigActive 2 / AACD 2.iso / AACD / Programming / perlman / man / perlpod.txt < prev    next >
Encoding:
Text File  |  1999-09-09  |  6.4 KB  |  166 lines
  1. NAME
  2.        perlpod - plain old documentation
  3.  
  4. DESCRIPTION
  5.        A pod-to-whatever translator reads a pod file paragraph by
  6.        paragraph, and translates it to the appropriate output
  7.        format.  There are three kinds of paragraphs:
  8.  
  9.        o   A verbatim paragraph, distinguished by being indented
  10.            (that is, it starts with space or tab).  It should be
  11.            reproduced exactly, with tabs assumed to be on
  12.            8-column boundaries.  There are no special formatting
  13.            escapes, so you can't italicize or anything like that.
  14.            A \ means \, and nothing else.
  15.  
  16.        o   A command.  All command paragraphs start with "=",
  17.            followed by an identifier, followed by arbitrary text
  18.            that the command can use however it pleases.
  19.            Currently recognized commands are
  20.  
  21.                =head1 heading
  22.                =head2 heading
  23.                =item text
  24.                =over N
  25.                =back
  26.                =cut
  27.                =pod
  28.  
  29.            The "=pod" directive does nothing beyond telling the
  30.            compiler to lay off of through the next "=cut".  It's
  31.            useful for adding another paragraph to the doc if
  32.            you're mixing up code and pod a lot.
  33.  
  34.            Head1 and head2 produce first and second level
  35.            headings, with the text on the same paragraph as
  36.            "=headn" forming the heading description.
  37.  
  38.            Item, over, and back require a little more
  39.            explanation: Over starts a section specifically for
  40.            the generation of a list using =item commands. At the
  41.            end of your list, use =back to end it. You will
  42.            probably want to give "4" as the number to =over, as
  43.            some formatters will use this for indention.  This
  44.            should probably be a default. Note also that there are
  45.            some basic rules to using =item: don't use them
  46.            outside of an =over/=back block, use at least one
  47.            inside an =over/=back block, you don't _have_ to
  48.            include the =back if the list just runs off the
  49.            document, and perhaps most importantly, keep the items
  50.            consistent: either use "=item *" for all of them, to
  51.            produce bullets, or use "=item 1.", "=item 2.", etc.,
  52.            to produce numbered lists, or use "=item foo", "=item
  53.            bar", etc., i.e., things that looks nothing like
  54.            bullets or numbers. If you start with bullets or
  55.            numbers, stick with them, as many formatters you the
  56.            first =item type to decide how to format the list.
  57.  
  58.            And don't forget, when using any command, that that
  59.            command lasts up until the end of the paragraph, not
  60.            the line. Hence in the examples below, you can see the
  61.            blank lines after each command to end it's paragraph.
  62.  
  63.            Some examples of lists include:
  64.  
  65.             =over 4
  66.  
  67.             =item *
  68.  
  69.             First item
  70.  
  71.             =item *
  72.  
  73.             Second item
  74.  
  75.             =back
  76.  
  77.             =over 4
  78.  
  79.             =item Foo()
  80.  
  81.             Description of Foo function
  82.  
  83.             =item Bar()
  84.  
  85.             Description of Bar function
  86.  
  87.             =back
  88.  
  89.        o   An ordinary block of text.  It will be filled, and
  90.            maybe even justified.  Certain interior sequences are
  91.            recognized both here and in commands:
  92.  
  93.                I<text>     italicize text, used for emphasis or variables
  94.                B<text>     embolden text, used for switches and programs
  95.                S<text>     text contains non-breaking spaces
  96.                C<code>     literal code
  97.                L<name>     A link (cross reference) to name
  98.                                L<name>             manpage
  99.                                L<name/ident>       item in manpage
  100.                                L<name/"sec">       section in other manpage
  101.                                L<"sec">            section in this manpage
  102.                                                    (the quotes are optional)
  103.                                L</"sec">           ditto
  104.                F<file>     Used for filenames
  105.                X<index>    An index entry
  106.                Z<>         A zero-width character
  107.  
  108.            That's it.  The intent is simplicity, not power.  I
  109.            wanted paragraphs to look like paragraphs (block
  110.            format), so that they stand out visually, and so that
  111.            I could run them through fmt easily to reformat them
  112.            (that's F7 in my version of vi).  I wanted the
  113.            translator (and not me) to worry about whether " or '
  114.            is a left quote or a right quote within filled text,
  115.            and I wanted it to leave the quotes alone dammit in
  116.            verbatim mode, so I could slurp in a working program,
  117.            shift it over 4 spaces, and have it print out, er,
  118.            verbatim.  And presumably in a constant width font.
  119.  
  120.            In particular, you can leave things like this verbatim
  121.            in your text:
  122.  
  123.                Perl
  124.                FILEHANDLE
  125.                $variable
  126.                function()
  127.                manpage(3r)
  128.  
  129.            Doubtless a few other commands or sequences will need
  130.            to be added along the way, but I've gotten along
  131.            surprisingly well with just these.
  132.  
  133.            Note that I'm not at all claiming this to be
  134.            sufficient for producing a book.  I'm just trying to
  135.            make an idiot-proof common source for nroff, TeX, and
  136.            other markup languages, as used for online
  137.            documentation.  Translators exist for pod2man  (that's
  138.            for nroff(1) and troff(1)), pod2html, pod2latex, and
  139.            pod2fm.
  140.  
  141. Embedding Pods in Perl Modules
  142.        You can embed pod documentation in your Perl scripts.
  143.        Start your documentation with a =head1 command at the beg,
  144.        and end it with an =cut command.  Perl will ignore the pod
  145.        text.  See any of the supplied library modules for
  146.        examples.  If you're going to put your pods at the end of
  147.        the file, and you're using an __END__ or __DATA__ cut
  148.        mark, make sure to put a blank line there before the first
  149.        pod directive.
  150.  
  151.            __END__
  152.  
  153.            =head1 NAME
  154.  
  155.            modern - I am a modern module
  156.  
  157.        If you had not had that blank line there, then the
  158.        translators wouldn't have seen it.
  159.  
  160. SEE ALSO
  161.        the pod2man manpage and the section on PODs: Embedded
  162.        Documentation in the perlsyn manpage
  163.  
  164. AUTHOR
  165.        Larry Wall
  166.